Sber Elementor Elearning

Данный файл содержит общее описание плагина. Более подробная информация находится в директории docs

Описание плагина

Sber Static Builder — это генератор статических сайтов, который преобразует страницы сайта WordPress в статический сайт, который можно разместить на своем сервере, у провайдера статического хостинга, в CDN или в системе обучения xAPI / Scorm. Сборка сайта значительно повышает его производительность и убирает множество потенциальных проблем с безопасностью.

Также все страницы сайта будут обернуты в iframe и запущены под управлением WP2 Wrapper. Под управлением оболочки страницы сайта превращаются в полноценный курс с информационными блоками, выводом медиа файлов, вопросами, прогрессом. Все виджеты из Elearning плагина также корректно работают в оболочке

Основные функции:

• Сборка страниц сайта в статику под разные окружения (Web / Scorm / xAPI)
• Настройка сборок: Меню / Загрузка / Доп. контент / Постобработка / Переводы — в Внешний вид → Плеер курса (кастомайзер); прочие ACF-опции сборок — в WP2 Platform → Настройки (при активном Platform)
• Интеграция с плагином Translate Press для перевода страниц сборки

Для кого:

• Создатели образовательных платформ: Разработчики, создающие образовательные платформы или сайты с обучающим контентом, могут использовать плагин для упрощения создания интерактивных курсов и тестов, интегрируя весь функционал непосредственно в WordPress.

Запуск проекта

Проект представляет из себя WordPress плагин. Для правильной работы плагина требуются

• PHP 8.2+
• WordPress 6+
• ACF Pro 6+

Интеграция с другими плагинами

• Translate Press - добавление возможности перевода страниц сборки
• My Private Site - поддержка сборки даже закрытых от посещения сайтов

Dev запуск

Для установки PHP зависимостей нужно запустить composer i в корне проекта. Для установки фронтенд зависимостей npm i в директории assets.

Фронтенд можно собрать в dev режиме с помощью npm run build:dev. С помощью npm run dev можно запустить watch сервер с автопересборкой файлов

Prod запуск

Для сборки проекта для продакшена есть /bin/zip.sh скрипт. Он установить prod зависимости composer и npm, уберет все лишние файлы и создаст zip архив плагина для дальнейшей установки

Конфигурация в админке

Есть возможность задать общие настройки для сборок на странице настроек (/wp-admin/edit.php?post_type=sber_static_build&page=sber-static-settings)

А так же задать настройки каждой сборки на ее странице в админке

Описание файлов

Основные PHP файлы (папка src)

Директория src содержит ключевые PHP-файлы, реализующие логику плагина,

Основные файлы и директории

• ArrayDataHandler.php: Управляет получением типизированных данных из массивов
• Helpers.php: Вспомогательные функции для различных задач, таких как генерация URL, преобразование данных и др.
• build_files_black_list.php: Массив с перечнем файлов, исключаемых из сборки статического курса.

Директория ACF

• acf_groups: json файлы с конфигурацией ACF полей для настроек всех сборок и конкретной сборки
• AcfFieldCustomPaths.php и AcfFieldPlayerJsSkin.php: кастомные поля ввода для acf
• MultilangFieldsFilter.php: скрытие полей для мультиязычности при отключенном плагине вопросов

Директория Ajax

• StaticBuildAjax.php: AJAX обработчик для получения статуса сборки и ее остановки

Директория Elementor

• Main.php: доработка фронтенд конфигов в сборке

Директория Entities

Все основные сущности для сборки курсов

• Builder: Набор классов для создания сборок
  • BuildController.php: Запуск сборок из очереди ожидания в сборку
  • Builder.php: Все этапы создания сборки
  • Elementor.php: Загрузка Elementor файлов в сборку
  • FilesBlackList.php: Фильтрация файлов и директорий сборки по черному списку
  • Config: Наборы правил для генерации конфигураций под разные окружения курса (Web / Scorm / xAPI).
  • Page: Набор классов для генерации одной сущности в сборку
• Enums: Перечисления, такие как BuildStatus.php, ConfigFileType.php, ConfigType.php, используемые для определения статусов и типов файлов в процессе сборки.
• Exceptions: Исключения, которые могут возникнуть в процессе генерации статического курса, например, BuildStoppedException.php, PageSkippedException.php.
• Languages: Набор классов для перевода страниц в сборке.

Директория ExtraPlugins

Интеграция с другими плагинами

Директория PluginBase

Стандартный набор классов для работы плагина

Директория WordPressCore

• CPT: Кастомные типы записей (CPT) для хранения и управления сборкой статических страниц.
  • SberStaticBuild.php: CPT для статической сборки, обеспечивающий её хранение и обработку.
  • Modal.php: CPT для модальных окон.
• ListTables: Поддержка пользовательских таблиц в админ-панели.
  • SberStaticBuildListTable.php - Таблица постов для сборок в админке
• MetaBoxes: Добавление мета-боксов.
  • SberStatic.php - метабокс с настройками сборки
• Posts: Набор классов для получения информации о разных сущностях плагина (StaticBuild, StaticPage, StaticModal, StaticPanel).

Фронтенд ресурсы (папка assets)

Директория assets содержит все необходимые ресурсы для фронтенд-части плагина, включая стили, скрипты и изображения, которые обеспечивают интерфейс и визуальное оформление курса

Директория src

• js: Основные JavaScript-файлы, организованные по функциям и модулям.
  • acf: Скрипты для интеграции с Advanced Custom Fields.
  • meta_boxes: Скрипт sber_static.js для функциональности мета-боксов, используемых в админке WordPress для управления сборкой.
  • src: Главные функциональные скрипты для фронтенда.
    • InfoUpdater.js: Обновляет информацию на страницах курса в реальном времени.
    • handleActions.js: Управляет действиями и событиями интерфейса курса.
    • mainPageSelect.js: Обработка выбора главной страницы, добавленной в сборку.
    • tableCheckboxes.js: Скрипт для управления чекбоксами в таблице выбора страниц курса.
  • actions: Обработчики действий в настройке курса (запуск и остановка)
  • utils: Вспомогательные утилиты
• scss: Стили для фронтенда
• webpack - Конфигурации и модули для Webpack, инструмента сборки JavaScript.
  • Parts/BasicPart.js - здесь находится список всех собираемых js файлов

Служебные скрипты (папка bin)

• install-wp-tests.sh - установка тестового окружения для PHPUnit
• phpcs.sh - Скрипт для запуска PHP_CodeSniffer для проверки стандартов кода. Запускается с помощью composer
• zip.sh - Скрипт для упаковки проекта в ZIP-архив. Можно запустить с помощью composer, но лучше запускать напрямую

Статический анализ PHPcs и Rector

Анализ кода производится автоматически с помощью PHP библиотек PHPcs, Rector и Psalm. Для упрощения запуска в composer.json добавлены скрипты. Скрипт для запуска всех линтеров code:fix

PHPcs

Проверяет стиль написания кода на соответствие стандартам WordPress с частичными послаблениями описанными в файле ruleset.xml

• phpcs - вывод краткой информации об ошибках
• phpcs:full - вывод подробной информации об ошибках
• phpcs:fix - автоматическое исправление ошибок

Rector

Проверяет логику кода и производит автоматический рефакторинг кода. Конфигурация библиотеки находится в файле rector.php

• rector:dry - вывод информации об ошибках
• rector:fix - автоисправление ошибок

Psalm

Psalm проверяет типизацию кода. Уровень проверки выставлен на дефолтные 2/8 (где 1 - это максимальный уровень проверок), поддержка 1 уровня требует большого количества работ

• psalm - показ ошибок типизации
• psalm:full - показ ошибок типизации и предупреждений с информацией

Системы непрерывной интеграции

• .gitlab-ci.yml - конфигурация для запуска CI в GitLab
• ci/docker_install.sh - Скрипт для установки зависимостей с использованием Docker в среде CI/CD.

WP2 Wrapper / Оболочка курса

Актуальная сборка WP2 Wrapper

Templates

Все шаблоны страниц и компонентов находятся в этой директории. Для их рендера можно воспользоваться функциями в главном файле плагина

Tests

Директория с автотестами на основе PHPUnit, но unit и интеграционных тестов недостаточно для полноценной проверки плагина. Нужны e2e тесты на основе Cypress (или аналога)

Перевод плагина

Все строки в плагине пишутся на английском языке с применением языковых WP функций (codex). В js коде для перевода нужно использовать i18n.js библиотеку, например wp.i18n.__('Copy id', 'sber-elementor-elearning'), важно использовать полный путь до функции перевода, чтобы она не была минимизирована webpack'ом и могла быть считана при подготовке перевода. Домен перевода соответствует имени плагина sber-elementor-elearning.

Composer скрипты для генерации файлов перевода:

• make-pot - генерация шаблонного файла перевода
• update-po - обновление всех файлов перевода на основе pot файла. После вызова этого скрипта нужно открыть все обновленные po файлы и проверить, что все строки переведены
• make-mo - генерация mo файлов на основе po файлов
• make-mo-json - генерация json файлов для перевода js кода

languages - Папка с файлами локализации, включающая .mo, .po, и .pot файлы для поддержки перевода и работы с различными языковыми версиями.